docs: add payment streams raw spec

[s-tikhomirov]

Add a functional specification for an MVP protocol describing payment streams for Logos services.

Payment streams enable time-based fund flows from users to service providers.

Key features:

• Two-level architecture with vaults and streams - vaults hold deposits backing multiple streams
• Stream lifecycle with states (ACTIVE, PAUSED, CLOSED) and transitions
• Time-based accrual with configurable rates
• Optional extensions for epoch caps, delivery receipts, and automatic settlement

This raw spec aims to facilitate discussions about implementation feasibility of this protocol on Nescience.

[s-tikhomirov]

To be added soon:

• off-chain protocol considerations (proof of stream ownership)
• illustrative section on potential EVM-based implementation

[chaitanyaprem]

LGTM

[jm-clius]

Thanks!

[Cofson]

Consider this scenario:

User has 1000 tokens in vault
T1: Issues VaultProof A to Provider A (500 tokens)
T2: Issues VaultProof B to Provider B (600 tokens)
T3: Creates stream A (500 tokens) ✅ 
T4: Creates stream B (600 tokens) ❌ Only 500 left!

Provider B accepted the VaultProof but can't actually get their stream. The spec says "user MAY issue VaultProofs only if sum doesn't exceed balance" but this can't be enforced without atomicity.

[s-tikhomirov]

I agree that this cannot be enforced. A provider may decide to not accept VaultProofs and instead wait for regular stream establishment before serving the first request. The idea is that accepting VaultProof for a single (first) request improves UX significantly while bringing only a limited (to single-response-worth) risk to the provider.

[s-tikhomirov]

Wording clarified in 233c0e4 (the "double-spending" issue remains a known limitation).

[Cofson]

Does it matter how frequently and if it can timeout?

[s-tikhomirov]

Frequency is up to the provider. I would imagine that any on-chain action generates a "receipt" (in Ethereum terminology), and that a provider subscribes to receipts about streams of their interest.

As for timeouts, this could happen as follows:

• at stream establishment, the provider remembers the planned depletion time of a stream;
• upon learning of any relevant receipts (pause, top-up), the provider updates the planned depletion time;
• shortly before depletion time, the provider double-checks stream status on-chain. If the depletion time represented on-chain is as provider expected, the provider stops service provision.

[Cofson]

The gas model might be very important when the spec needs to go draft/stable because of possible attack vectors. Just commenting for visibility.

[Cofson]

Overall, this is really solid work - works as a raw spec perfectly. However, there are some gaps that should be addressed before moving to draft status. I would suggest working on some edge cases and perhaps even work a bit with the security team to identify and fix some of the gaps.