onionmessage

type GraphNodeResolver ¶

type GraphNodeResolver struct {
	// contains filtered or unexported fields
}

GraphNodeResolver resolves node public keys from short channel IDs using the channel graph. It maintains an LRU cache to avoid repeated database lookups for frequently used SCIDs.

func NewGraphNodeResolver(graph *graphdb.ChannelGraph,
	ourPub *btcec.PublicKey) *GraphNodeResolver

func (r *GraphNodeResolver) RemotePubFromSCID(ctx context.Context,
	scid lnwire.ShortChannelID) (*btcec.PublicKey, error)

type IngressLimiter ¶

type IngressLimiter interface {
	// AllowN reports whether an onion message of n bytes from the
	// given peer is permitted. A successful result wraps fn.Unit; a
	// rejection wraps either ErrPeerRateLimit or ErrGlobalRateLimit
	// depending on which bucket fired. Callers use errors.Is against
	// those sentinels to pick their log / metric / drop path.
	//
	// Per-peer state is retained for the lifetime of the process so
	// that a peer cannot reset its bucket by cycling the connection;
	// see the PeerRateLimiter doc for the memory-bound argument.
	AllowN(peer [33]byte, n int) fn.Result[fn.Unit]

	// FirstPeerDropClaim atomically returns true exactly once, on
	// the first call, and is intended to gate a one-shot info log
	// when the per-peer limiter first trips.
	FirstPeerDropClaim() bool

	// FirstGlobalDropClaim atomically returns true exactly once, on
	// the first call, and is intended to gate a one-shot info log
	// when the global limiter first trips.
	FirstGlobalDropClaim() bool
}

IngressLimiter is the combined per-peer + global rate limiter surface consumed by the onion message ingress path. It hides the split between the two underlying buckets so callers in peer/brontide.go only need to thread a single object through Config and call a single method on every incoming onion message. The per-peer bucket is always checked first so that a hostile peer whose own budget is already empty cannot burn global tokens on every rejected attempt and starve legitimate peers.

Implementations must be safe for concurrent use from per-peer readHandler goroutines. A nil IngressLimiter is a valid "disabled" sentinel at call sites and means "accept everything".

func NewIngressLimiter(peer *PeerRateLimiter,
	global RateLimiter) IngressLimiter

type NodeIDResolver ¶

type NodeIDResolver interface {
	RemotePubFromSCID(ctx context.Context,
		scid lnwire.ShortChannelID) (*btcec.PublicKey, error)
}

NodeIDResolver defines an interface to resolve a node public key from a short channel ID.

type OnionActorFactory ¶

type OnionActorFactory func(system *actor.ActorSystem,
	peerPubKey [33]byte,
	opts ...actor.ActorOption[*Request, *Response]) (OnionPeerActorRef,
	error)

OnionActorFactory is a function that spawns a new OnionPeerActor for a given peer within the actor system. The factory captures shared dependencies (router, resolver, sender, dispatcher) and only requires per-peer parameters at spawn time. Callers may pass ActorOptions to customise the mailbox (size, drop predicate, etc.) on a per-peer basis.

func NewOnionActorFactory(router OnionRouter, resolver NodeIDResolver,
	peerSender PeerMessageSender,
	dispatcher OnionMessageUpdateDispatcher) OnionActorFactory

type OnionMessageUpdate ¶

type OnionMessageUpdate struct {
	// Peer is the peer pubkey
	Peer [33]byte

	// PathKey is the route blinding ephemeral pubkey to be used for
	// the onion message.
	PathKey [33]byte

	// OnionBlob is the raw serialized mix header used to relay messages in
	// a privacy-preserving manner. This blob should be handled in the same
	// manner as onions used to route HTLCs, with the exception that it uses
	// blinded routes by default.
	OnionBlob []byte

	// CustomRecords contains any custom TLV records included in the
	// payload.
	CustomRecords record.CustomSet

	// ReplyPath contains the reply path information for the onion message.
	ReplyPath *sphinx.BlindedPath

	// EncryptedRecipientData contains the encrypted recipient data for the
	// onion message, created by the creator of the blinded route. This is
	// the receiver for the last leg of the route, and the sender for the
	// first leg up to the introduction point.
	EncryptedRecipientData []byte
}

OnionMessageUpdate is onion message update dispatched to any potential subscriber.

type OnionMessageUpdateDispatcher ¶

type OnionMessageUpdateDispatcher interface {
	// SendUpdate sends an onion message update to all subscribers.
	SendUpdate(update any) error
}

OnionMessageUpdateDispatcher dispatches onion message updates to subscribers.

type OnionPeerActor ¶

type OnionPeerActor struct {
	// contains filtered or unexported fields
}

OnionPeerActor handles the full onion message processing pipeline for a specific peer connection. It decodes incoming onion messages, determines the routing action (forward or deliver), executes the action, and dispatches updates to subscribers.

func (a *OnionPeerActor) Receive(ctx context.Context,
	req *Request) fn.Result[*Response]

type OnionPeerActorRef ¶

type OnionPeerActorRef actor.ActorRef[*Request, *Response]

OnionPeerActorRef is a reference to an OnionPeerActor.

type OnionRouter ¶

type OnionRouter interface {
	// ProcessOnionPacket processes an onion packet and returns the
	// processed result.
	ProcessOnionPacket(pkt *sphinx.OnionPacket, assocData []byte,
		incomingCltv uint32,
		opts ...sphinx.ProcessOnionOpt) (*sphinx.ProcessedPacket, error)

	// DecryptBlindedHopData decrypts the encrypted hop data using the
	// given path key.
	DecryptBlindedHopData(pathKey *btcec.PublicKey,
		encData []byte) ([]byte, error)

	// NextEphemeral derives the next ephemeral key from the current path
	// key.
	NextEphemeral(
		currentPathKey *btcec.PublicKey) (*btcec.PublicKey, error)
}

OnionRouter wraps the sphinx router operations needed for onion message processing.

type PeeledHop ¶

type PeeledHop struct {
	EncryptedData []byte
	Payload       *lnwire.OnionMessagePayload
	IsFinal       bool
}

PeeledHop captures decrypted state for a single hop when peeling an onion.

func PeelOnionLayers(t *testing.T, privKeys []*btcec.PrivateKey,
	msg *lnwire.OnionMessage) []PeeledHop

type PeerMessageSender ¶

type PeerMessageSender interface {
	// SendToPeer sends an onion message to the peer identified by the
	// given compressed public key.
	SendToPeer(pubKey [33]byte, msg *lnwire.OnionMessage) error
}

PeerMessageSender sends onion messages to peers identified by public key.

type PeerRateLimiter ¶

type PeerRateLimiter struct {
	// contains filtered or unexported fields
}

PeerRateLimiter is a registry of per-peer onion message token buckets, keyed by the peer's compressed public key. Tokens are bytes: callers pass the on-the-wire size of each message to AllowN and the per-peer bucket is debited accordingly. Buckets are created lazily on the first call to AllowN for a given peer and retained for the lifetime of the process. When the configured rate or burst is zero the registry operates in disabled mode and AllowN is a no-op.

Retention across disconnect is load-bearing. Without it, a peer could drain its burst, disconnect, reconnect, and get a fresh full-burst bucket on every cycle, effectively promoting the global limiter into its per-peer rate and using the shared budget as a personal allowance until the global bucket trips. By keeping the bucket, a drained peer stays drained until its bucket naturally refills regardless of how often it cycles the connection, and the per-peer rate becomes a real ceiling rather than a per-connection ceiling.

The memory cost of retention is bounded by the number of channel peers that have ever sent an onion message: the ingress call site gates AllowN on the peer having at least one open channel before touching this registry, so random connecting strangers never allocate a bucket. At a realistic few hundred to few thousand channel partners and ~200 bytes per entry (rate.Limiter plus SyncMap overhead), the registry stays comfortably sub-megabyte for the lifetime of the process.

The underlying bucket registry is an lnutils.SyncMap rather than a plain map guarded by a mutex. Per-peer keys are stable for the lifetime of the connection and the common path is a Load hit, which sync.Map serves without any write contention across peers. A plain map would serialize every hot-path AllowN call behind a single mutex even though rate.Limiter is already safe for concurrent use.

func NewPeerRateLimiter(kbps uint64, burstBytes uint64) *PeerRateLimiter

func (p *PeerRateLimiter) AllowN(peer [33]byte, n int) bool

func (p *PeerRateLimiter) Dropped() uint64

func (p *PeerRateLimiter) FirstDropClaim() bool

type RateLimiter ¶

type RateLimiter interface {
	// AllowN reports whether an onion message of n bytes is permitted
	// to proceed at the current instant. It must be non-blocking and
	// safe for concurrent use.
	AllowN(n int) bool
}

RateLimiter is the minimal token-bucket interface used at the onion message ingress path. Tokens are bytes: each call reports whether a message of size n bytes is permitted to proceed, and on success consumes n bytes from the underlying bucket. The interface is satisfied by *rate.Limiter (via a small counting wrapper) and a noop implementation used when a limit is configured as zero (disabled). It exists so that callers and tests can substitute alternate implementations without taking a hard dependency on the x/time/rate package.

Implementations of AllowN must be safe for concurrent use by multiple goroutines; the ingress call site invokes it from per-peer readHandler goroutines without additional synchronization.

func NewGlobalLimiter(kbps uint64, burstBytes uint64) RateLimiter

type Request ¶

type Request struct {
	// Embed BaseMessage to satisfy the actor package Message interface.
	actor.BaseMessage
	// contains filtered or unexported fields
}

Request is a message sent to an OnionPeerActor when an onion message is received from the peer. The actor processes the message through the full onion message pipeline: decode, decrypt, route, and forward/deliver.

func NewRequest(msg lnwire.OnionMessage) *Request

func (m *Request) MessageType() string

type Response ¶

type Response struct {
	actor.BaseMessage
	Success bool
}

Response is the response message sent back from an OnionPeerActor after processing an incoming onion message.

func (m *Response) MessageType() string