Relay monetization groundwork (FanoutTree/DirectStream)

[marcus-pousette]

Context

This is a sub-issue under #577 (Scalable fanout pubsub).

Long term, we want relays to be able to earn money (potentially crypto) for forwarding data, without turning the data plane into a heavy “payment protocol”.

What we already have (today)

• FanoutTree has a bidPerByte concept in JOIN_REQ and tracker messages, and basic bid-based selection/kicking when overloaded.
• The implementation tracks a coarse metrics.earnings based on forwarded payload bytes.

This is a good start, but it is not yet a coherent “monetization-ready” foundation.

The gap

To actually monetize relaying in production we need groundwork in two places:

1. Policy + pricing semantics

• Clarify what bidPerByte means.
  • Is it the child’s offered payment?
  • The relay’s ask/minimum?
  • A generic score?
• Decide the unit we optimize for:
  • pay-per-byte (bandwidth)
  • pay-per-time (reserved slot / reserved bandwidth)
  • hybrid (reserve + overage)

2. Metering + settlement hooks (without bloating the hot path)

• We need reliable per-peer/per-channel accounting for bytes forwarded, drops, queueing, and priorities.
• We need a way to export those numbers to an app/wallet and/or to generate periodic settlement records.
• We should avoid adding per-message cryptographic payment material to the data plane.

Proposal: minimal, future-proof foundation

A. Define pricing semantics + protocol fields

• Introduce an explicit concept of relay ask (e.g. askPerByte or minBidPerByte) separate from the joiner’s bidPerByte.
• Make trackers carry the relay ask so joiners can choose parents predictably.
• Allow dynamic updates (relay ask/capacity changes) via TRACKER_ANNOUNCE refresh.

B. Add stream-level metering hooks

In @peerbit/stream (or a thin layer next to it), add a lightweight metering interface such as:

• per-connection counters: bytes written/queued/dropped by lane/priority
• drop reasons and backpressure signals
• callbacks/events that higher layers can subscribe to (for accounting and UX)

This should be optional and cheap when disabled.

C. Expose per-child accounting in FanoutTree

• Track per-child forwarded bytes (payload + framing), drops, kick reasons, and achieved delivery rate.
• Expose as:
  • extended getChannelStats()
  • events for external accounting sinks

D. Settlement hook (out of scope for v1, but define shape)

• Define an optional control-plane message for periodic signed counters/receipts between parent and child.
• Keep it aggregated (e.g. per 1s or per 1MB), not per message.
• No on-chain integration required initially; we just want a clean interface boundary.

E. Simulation support

• Extend sims to include:
  • subscriber “budgets” / credit limits
  • relay ask
  • policy: prioritize higher bids under upload caps
• Output:
  • earnings distribution per relay
  • fairness metrics
  • effect on latency and delivery under churn

Acceptance criteria (for this issue)

• We can run local sims where:
  • relays advertise an ask
  • subscribers choose parents based on ask + capacity
  • upload caps are respected
  • higher bids get more reliable service under overload
  • we can export per-relay accounting suitable for later settlement

Non-goals (for now)

• Byzantine proofs-of-forwarding / Sybil resistance (document assumptions and keep doors open).
• Full on-chain settlement.