Crate hopr_lib

Expand description

HOPR library creating a unified Hopr object that can be used on its own, as well as integrated into other systems and libraries.

The Hopr object is standalone, meaning that once it is constructed and run, it will perform its functionality autonomously. The API it offers serves as a high-level integration point for other applications and utilities, but offers a complete and fully featured HOPR node stripped from top level functionality such as the REST API, key management…

The intended way to use hopr_lib is for a specific tool to be built on top of it; should the default hoprd implementation not be acceptable.

For most of the practical use cases, the hoprd application should be a preferable choice.

Re-exports§

pub use crate::config::SafeModule;
pub use crate::constants::MIN_NATIVE_BALANCE;
pub use crate::constants::SUGGESTED_NATIVE_BALANCE;
pub use crate::errors::HoprLibError;
pub use crate::errors::HoprStatusError;
pub use hopr_api as api;

Modules§

api: hopr-api
builder: Builder module for the Hopr object. Type-state builder for constructing a Hopr node.
config: Configuration-related public types
constants: Various public constants.
crypto_traits: Re-exports from the generic cryptographic traits.
errors: Lists all errors thrown from this library.
helpers 🔒: Helper functions.
session: HoprSession object providing the session functionality over the HOPR transport
socket
utils: Utility module with helper types and functionality over hopr-lib behavior.

Structs§

AbortableList: List of Abortable tasks with each task identified by a unique key of type T.
AccountEntry: Represents a node announcement entry on the blockchain. This contains the node’s public key and optional announcement information (multiaddress).
AcknowledgedTicket: Contains acknowledgment information and the respective ticket
Acknowledgement: Unverified packet acknowledgement.
Address: Represents an Ethereum address
AnnouncedPeer: A peer that has been announced and discovered by the node.
AnnouncementData: Structure containing data used for an on-chain announcement. That is an optional decapsulated multiaddress (with the /p2p/{peer_id} suffix removed) and mandatory keybinding KeyBinding.
ApplicationData: Represents the to-be-sent or received decrypted packet carrying the application-layer data.
ApplicationDataIn: Wrapper for incoming ApplicationData with optional [IncomingPacketInfo].
ApplicationDataOut: Wrapper for outgoing ApplicationData with optional [IncomingPacketInfo].
Balance: Represents a non-negative balance of some Currency.
Blake3: An incremental hash state that can accept any number of writes.
Blake3Output: An incremental reader for extended output, returned by Hasher::finalize_xof.
BoundedVec: Wrapper for Vec that has an explicit upper bound on the number of elements. The Structure remains heap-allocated to avoid blowing up the size of types where it is used.
ChainKeypair: Represents a keypair consisting of a secp256k1 private and public key
ChainPath: Represents a NonEmptyPath that completely specifies a route using Addresses.
ChainSignature: Represents an ECDSA signature based on the secp256k1 curve with a recoverable public key. When signing messages, Keccak256 is used as the hash function; sign_hash operates on an arbitrary pre-computed hash.
Challenge: Contains the complete Proof-of-Relay challenge is a secp256k1 curve point.
ChannelBuilder: Builder for ChannelEntry.
ChannelEntry: Overall description of a channel
ChannelParties: An immutable pair of addresses representing parties of a channel.
ChannelStats: Contains ticket statistics for an incoming channel.
ConnectedUdpStream: Mimics TCP-like stream functionality on a UDP socket by restricting it to a single counterparty and implements [tokio::io::AsyncRead] and [tokio::io::AsyncWrite]. The instance must always be constructed using a UdpStreamBuilder.
CorruptedChannelEntry: A wrapper around ChannelId representing a Channel that is corrupted.
EthereumChallenge: Represents and Ethereum challenge.
HalfKey: Represents a half-key used for the Proof-of-Relay.
HalfKeyChallenge: Represents a challenge for the half-key in Proof of Relay.
HashBase: Represents a generic 256-bit hash value.
HopRouting: Public routing configuration for session opening in hopr-lib.
Hopr: HOPR main object providing the entire HOPR node functionality
HoprKeys
HoprProtocolConfig: Complete configuration of the HOPR protocol stack.
HoprSenderId: Identifier of a single packet sender.
HoprSession: Represents the Session protocol socket over HOPR.
HoprSessionClientConfig: Session client configuration for hopr-lib.
HoprSessionConfigurator: Allows configuration of one specific HoprSession.
HoprTransport: Interface into the physical transport mechanism allowing all off-chain HOPR-related tasks on the transport.
IncomingSession: Wrapper for incoming HoprSession along with other information extracted from the Start protocol during the session establishment.
IvKey: Convenience container for IV and key of a given primitive T.
K256EcdsaSigningEngine: ECDSA signing engine based on the pure Rust k256 crate.
KeyBinding: Holds the signed binding of the chain key and the packet key.
KeyIdent: Identifier of public keys.
Multiaddr: Representation of a Multiaddr.
NativeEcdsaSigningEngine: ECDSA signing engine based on the fast secp256k1 crate.
NeighborTelemetry: Intermediate neighbor telemetry object.
NoPathSelector: A path selector that does not resolve any path, always returns PathError::PathNotFound.
NodeComponentStatuses: Per-component status report for the HOPR node.
OffchainKeypair: Represents a keypair consisting of an Ed25519 private and public key
OffchainPublicKey: Represents an Ed25519 public key.
OffchainSignature: Represents an EdDSA signature using the Ed25519 Edwards curve.
PathTelemetry: Path telemetry data for multi-hop loopback probing.
PeerId: Identifier of a peer of the network.
PeerProtocolCounterRegistry: Thread-safe registry of per-peer protocol conformance counters.
PingQueryReplier: Helper object allowing to send a ping query as a wrapped channel combination that can be filled up on the transport part and awaited locally by the Pinger.
Poly1305: The Poly1305 universal hash function.
PublicKey: Represents a secp256k1 public key.
RedeemableTicket: Represents a winning ticket that can be successfully redeemed on-chain.
Response: Contains a response upon ticket acknowledgement It is equivalent to a non-zero secret scalar on secp256k1 (EC private key).
SecretValue: Represents a secret value of a fixed length that is zeroized on drop. Secret values are always compared in constant time. The default value is all zeroes.
SerializableLog: A type containing selected fields from the eth_getLogs RPC calls.
SessionClientConfig: Configuration for the session.
SessionId: Unique ID of a specific Session in a certain direction.
SimplePseudonym: Represents a simple UUID-like pseudonym consisting of 10 bytes.
SrcDstPair: A pair of source and destination addresses representing a channel.
SurbBalancerConfig: Configuration for the SurbBalancer.
TagAllocatorConfig: Configuration for the tag allocator partitions.
Ticket: Contains the overall description of a ticket with a signature.
TicketBuilder: Builder for the Ticket and VerifiedTicket.
TicketId: A ticket is uniquely identified by its channel id, ticket index and epoch.
TransferableWinningTicket: Represents a ticket that could be transferred over the wire and independently verified again by the other party.
TransportPath: A NonEmptyPath that can be used to route packets using OffchainPublicKey.
UdpStreamBuilder: Builder object for the ConnectedUdpStream.
UnacknowledgedTicket: Represents a VerifiedTicket with an unknown other part of the HalfKey. Once the other HalfKey is known (forming a Response), it can be acknowledged.
Utc: The UTC time zone. This is the most efficient time zone when you don’t need the local time. It is also used as an offset (which is also a dummy type).
ValidatedPath: Represents NonEmptyPath that has been resolved and validated.
VerifiedAcknowledgement: Represents packet acknowledgement whose signature has been already verified.
VerifiedTicket: Holds a ticket that has been already verified. This structure guarantees that Ticket::get_hash() of VerifiedTicket::verified_ticket() is always equal to VerifiedTicket::verified_hash
VrfParameters: Bundles values given to the smart contract to prove that a ticket is a win.
WinningProbability: Represents a ticket-winning probability.
WxHOPR: Represents wxHOPR token Currency.
XDai: Represents xDai coin Currency.
XHOPR: Represents xHOPR token Currency.

Enums§

AccountType: Type of the node account.
AcknowledgedTicketStatus: Status of the acknowledged ticket.
AnnouncementOrigin: Origin of a peer announcement — how the node learned about this peer.
ChannelChange: Lists possible changes on a channel entry update
ChannelDirection: Describes a direction of node’s own channel. The direction of a channel that is not own is undefined.
ChannelStatus: Describes status of a channel
ChannelStatusDiscriminants: Auto-generated discriminant enum variants
CoreTypesError: Enumeration of all core type related errors.
CryptoError: Enumeration of all cryptography-related errors in this crate.
DestinationRouting: Routing information containing forward or return routing options.
EitherErr: Allows combining two errors L and R into a single error type that acts transparently.
ForeignDataMode: Defines what happens when data from another SocketAddr arrives into the ConnectedUdpStream (other than the one that is considered a counterparty for that instance).
GeneralError: Listing of some general re-usable errors
Health: Network health represented with colors, where green is the best and red is the worst possible observed network quality.
HoprLibProcess 🔒: Long-running tasks that are spawned by the HOPR node.
HoprState: An enum representing the current state of the HOPR node.
HoprTransportProcess
IdentityRetrievalModes
IpOrHost: Implements a host name with port. This could be either a DNS name with port or an IP address with port represented by std::net::SocketAddr.
IpProtocol: Lists some of the IP protocols.
NodeId: Uniquely identifies a HOPR node either by its Address or OffchainPublicKey.
PendingAcknowledgement: Contains either unacknowledged ticket if we’re waiting for the acknowledgement as a relayer or information if we wait for the acknowledgement as a sender.
ProbeError
Protocol: Protocol describes all possible multiaddress protocols.
RedemptionResult: Indicates a non-error result of ticket redemption.
ResolvedTransportRouting: Contains the resolved routing information for the packet.
RoutingOptions: Represents routing options in a mixnet with a maximum number of hops.
SealedHost: Contains optionally encrypted IpOrHost.
SessionAckMode
SessionCapability: Individual capabilities of a Session.
SessionLifecycleState
SessionManagerError
SessionTarget: Defines what should happen with the data at the recipient where the data from the established session are supposed to be forwarded to some target.
SurbMatcher: Allows finding saved SURBs based on different criteria.
Tag: Tags distinguishing different application-layer protocols.
TransportSessionError: Enumeration of errors thrown from this library.
UdpStreamParallelism: Determines how many parallel readers or writer sockets should be bound in ConnectedUdpStream.

Constants§

APPLICATION_TAG_RANGE
DEFAULT_MAXIMUM_INCOMING_TICKET_WIN_PROB: Default maximum incoming ticket winning probability, above which tickets will not be accepted due to privacy.
DEFAULT_MINIMUM_INCOMING_TICKET_WIN_PROB: Default required minimum incoming ticket winning probability
INTERMEDIATE_HOPS: Number of intermediate hops: 3 relayers and 1 destination
MIN_BATCH_SIZE: Minimum batch size of acknowledgements to use EdDSA batch verification algorithm.
NODE_READY_TIMEOUT 🔒: Time to wait until the node’s keybinding appears on-chain
PACKET_TAG_LENGTH: Length of a packet tag
REDEEM_CALL_SELECTOR: Define the selector for the redeemTicketCall to avoid importing the entire hopr-bindings crate for one single constant. This value should be updated with the function interface changes.
SESSION_MTU: Number of bytes that can be sent in a single Session protocol payload.
SURB_ID_SIZE: Size of the HoprSurbId in bytes.
SURB_SIZE: Size of the HOPR SURB in bytes.

Traits§

Abortable: Abstraction over tasks that can be aborted (such as join or abort handles).
AsUnixTimestamp: A trait that’s added an extension method to represent a time object as Duration since Unix epoch.
BytesEncodable: Represents a type that can be encoded to/decoded from a fixed-sized byte array of size N.
BytesRepresentable: Represents a type already internally represented by a fixed size byte array, and therefore requires no memory allocation to represent the type in binary encoding.
Currency: Represents a general currency - like a token or a coin.
EcdsaEngine: Trait for ECDSA signature engines.
EdgeLinkObservable: Trait for recording and querying transport-level link quality metrics for a transport link.
HoprNodeOperations: General operations performed by a HOPR node.
HoprSessionClientOperations: Trait for establishing HOPR sessions to remote destinations.
IncentiveChannelOperations: Channel management, balance queries, withdrawals, and chain info.
IncentiveRedeemOperations: Ticket redemption and statistics.
IntoEndian: Extension trait for fixed size numbers to allow conversion to/from endian representations.
KeyIdMapping: Trait that defines 1:1 mapper between key identifiers and public keys.
Keypair: Represents a generic key pair The keypair contains a private key and public key. Must be comparable in constant time and zeroized on drop.
NetworkStreamControl: Control object for the opening and receiving of network connections in the form of network streams.
NetworkView: Trait representing a read-only view of the network state.
NonEmptyPath: A Path that is guaranteed to have at least one hop - the destination.
Path: Base implementation of an abstract path.
PathAddressResolver: Allows resolution of OffchainPublicKey for a given Address or vice versa and retrieval of ChannelEntry based on the parties.
PathSelector: Trait for implementing a custom path selection algorithm from the channel graph.
Pseudonym: Pseudonym used to identify the creator of a SURB. This allows indexing SURB and LocalSURBEntry at both parties.
SaturatingSub: A trait that adds an extension method to perform saturated substractions on SystemTime instances.
TicketManagement: API for managing winning (redeemable) tickets in incoming channels.
TicketManagementExt: Asynchronous extension trait for TicketManagement that adds convenience methods for ticket management.
ToHex: A generic type that can be converted to a hexadecimal string.
TransportOperations: Minimal transport operations that require the full transport stack.
UnitaryFloatOps: Allows type to be multiplied and divided by a float in range [0.0, 1.0].

Functions§

blake3_hash: The default hash function.
decapsulate_multiaddress: Decapsulates the multiaddress (= strips the /p2p/<peer_id> suffix). If it is already decapsulated, the function is an identity.
derive_vrf_parameters: Takes a private key, the corresponding Ethereum address and a payload and creates all parameters that are required by the smart contract to prove that a ticket is a win.
f64_approx_eq: Approximately compares two double-precision floats.
generate_channel_id: Generates channel ID hash from source and destination addresses.
is_public: Check if an IP address is a public/routable one.
is_public_address: Check if a multiaddress contains a public/routable IP address.
k256_scalar_from_bytes: Creates secp256k1 secret scalar from the given bytes. Note that this function allows zero scalars.
network_health_to_status 🔒: Maps Health into a ComponentStatus for a named component.
peer_id_to_offchain_key: Converts a PeerId to an OffchainPublicKey.
peer_id_to_public_key: PeerId -> OffchainPublicKey is a CPU-intensive blocking operation.
prepare_tokio_runtime: Prepare an optimized version of the tokio runtime setup for hopr-lib specifically.
sample_secp256k1_field_element: Sample a random secp256k1 field element that can represent a valid secp256k1 point.
seal_data: CURRENTLY NOT IMPLEMENTED, see https://github.com/hoprnet/hoprnet/issues/7172
to_hex_shortened: Converts the given data into a hex string, removing the middle part of the string if it is longer than M of hex characters.
transfer_session: Convenience function to copy data in both directions between a Session and arbitrary async IO stream. This function is only available with Tokio and will panic with other runtimes.
unseal_data: CURRENTLY NOT IMPLEMENTED, see https://github.com/hoprnet/hoprnet/issues/7172
x25519_scalar_from_bytes: Creates X25519 secret scalar (also compatible with Ed25519 scalar) from the given bytes. This function ensures the value is pre-multiplied by the curve’s co-factor and already reduced mod 2^255-19.

Type Aliases§

Aes128Ctr: AES with 128-bit key in counter-mode (with big-endian counter).
ChaCha20: ChaCha20 stream cipher (RFC 8439 version with 96-bit nonce)
ChannelId: Alias for the Hash representing a channel ID.
ChannelPath: A path of Addresses representing intermediate hops in a payment channel route.
EncodedWinProb: Winning probability encoded in 7-byte representation
Hash: Represents an Ethereum 256-bit hash value.
HashFast: Represents an alternative 256-bit hash value computed via a faster hashing algorithm.
HoprBalance: Balance denominated in wxHOPR (wrapped xHOPR) tokens.
HoprPseudonym: Alias for the Pseudonym used in the HOPR protocol.
HoprSurbId: An ID that uniquely identifies SURB for a certain pseudonym.
HoprTransportIO: Type alias used to send and receive transport data via a running HOPR node.
Keccak256: Keccak-256 hasher state.
PacketTag: Represents a fixed size packet verification tag
PathId: Identifier for a path traversed using an allowed DestinationRouting over the network.
SecretKey: Represents a 256-bit secret key of fixed length. The value is auto-zeroized on drop.
SecretKey16: Represents a 128-bit secret key of fixed length. The value is auto-zeroized on drop.
ServiceId: Describes a node service target. These are specialized SessionTargets that are local to the Exit node and have different purposes, such as Cover Traffic.
SessionCapabilities: Set of Session capabilities.
Sha3_256: SHA-3-256 hasher state.
Signature: Default ECDSA signature type using the native secp256k1 signing engine.
TicketEvents 🔒
U256: 256-bit unsigned integer type alias for [primitive_types::U256].
XDaiBalance: Balance denominated in xDai (native gas token).
XHoprBalance: Balance denominated in xHOPR tokens.

Crate hopr_lib

Crate hopr_lib Copy item path

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate hopr_lib