clarify MVP pricing; generalize reputation scores; minor edits

incentivization.md

@@ -4,8 +4,8 @@ TWN needs incentivization (shortened to i13n) to ensure proper node behavior.
 
 The goal of this document is to outline and contextualize our approach to TWN i13n.
 After providing an overview of Waku and relevant prior work,
-we focus on Waku Store - a client-server protocol for quer
+we focus on Waku Store - a client-server protocol for querying historical messages.
-We then introduce a minimal viable addition to Store to enable i13n, and list research directions for future work.
+We introduce a minimal viable addition to Store to enable i13n, and list research directions for future work.
 
 # Incentivization in decentralized networks
 ## Incentivization tools
@@ -21,9 +21,9 @@ In other words, there are four quadrants:
 - reputation punishment: the node's reputation decreases if it behaves badly.
 
 Reputation only works if high reputation brings tangible benefits.
-For example, if nodes chose neighbors based on reputation, low-reputation nodes may miss out on potential revenue.
+For example, if nodes chose neighbors based on reputation, low-reputation nodes miss out on potential revenue.
 Reputation scores may be local (a node assigns scores to its neighbors) or global (each node gets a uniform score).
-Global reputation in its simplest implementation involves a trusted third party,
+Global reputation in its simplest form involves a trusted third party,
 although decentralized approaches are also possible.
 
 ## Prior work
@@ -32,20 +32,20 @@ We may split incentivized decentralized networks into early file-sharing, blockc
 
 ### Early P2P file-sharing
 
-Early P2P file-sharing networks employed reputation-based approaches and sticky defaults.
+Early P2P file-sharing networks employ reputation-based approaches and sticky defaults.
-For instance, in BitTorrent, a peer by default shares pieces of a file before having received it in whole.
+For instance, the BitTorrent protocol rewards uploading peers with faster downloads.
-At the same time, the bandwidth that a peer can use depends on how much is has shared previously.
+The download bandwidth available to a peer depends on how much it has uploaded.
-This policy rewards nodes who share by allowing them to download file faster.
+Moreover, peers share pieces of a file before having received it in whole.
-While this reward is not monetary, it has proven to be working in practice.
+This non-monetary i13n policy has been proved to work in practice.
 
 ### Blockchains
 
-Bitcoin has introduced native monetary i13n in a P2P network with proof-of-work (PoW).
+Bitcoin has introduced proof-of-work (PoW) for native monetary rewards in a P2P network.
-PoW miners are automatically rewarded with newly mined coins for generating blocks.
+PoW miners are automatically assigned newly mined coins for generating blocks.
 There are no intrinsic monetary punishments in Bitcoin.
 However, miners must expend physical resources before claiming the reward.
-Proof-of-stake (PoS) algorithms introduce intrinsic monetary punishments.
+Proof-of-stake (PoS), used in Ethereum and many other cryptocurrencies, introduces intrinsic monetary punishments.
-PoS validators lock up (stake) native tokens to get rewarded for validating blocks or slashed for misbehavior.
+PoS validators lock up (stake) native tokens and get rewarded for validating blocks or slashed for misbehavior.
 
 ### Decentralized storage
 
@@ -54,31 +54,31 @@ Their i13n methods combine techniques from early P2P file-sharing with blockchai
 
 # Waku background
 
-Waku is a family of protocols (see [architecture](https://waku.org/about/architect)) for a modular decentralized censorship-resistant P2P communications network.
+Waku is a family of protocols (see [architecture](https://waku.org/about/architect)) for a modular privacy-preserving censorship-resistant decentralized communications network.
 The backbone of Waku is the Relay protocol (and its spam-protected version [RLN-Relay](https://rfc.vac.dev/spec/17/)).
 Additionally, there are light protocols: Filter, Store, and Lightpush.
 Light protocols are also referred to as client-server protocols and request-response protocols.
 
-A server is a node running Relay and Store (server-side).
+A server is a node running Relay and a server-side of at least one light protocol.
-A client is a node running a client-side of any of the light protocols as a light node or a client.
+A client is a node running a client-side of any of the light protocols.
 A server may sometimes be referred to as a full node, and a client as a light node.
 There is no strict definition of a full node vs a light node in Waku (see [discussion](https://github.com/waku-org/research/issues/28)).
 
 In light protocols, a client sends a request to a server, and a server performs some actions and returns a response:
 - [[Filter]]: the server will relay (only) messages that pass a filter to the client;
-- [[Store]]: the server responds with messages broadcast earlier within the specified time frame;
+- [[Store]]: the server responds with messages relayed within the specified earlier time frame;
 - [[Lightpush]]: the server publishes the client's message to the Relay network.
 
 ## Waku i13n challenges
 
 Waku lacks consensus or a native token, which brings it closer to reputation-incentivized file-sharing systems.
-Indeed, currently Waku only operates under reputation-based rewards and punishments.
+As of late 2023, Waku only operates under reputation-based rewards and punishments.
 While [RLN-Relay](https://rfc.vac.dev/spec/17/) adds monetary punishments for spammers, slashing is yet to be activated.
 
 Monetary rewards and punishments should ideally be atomically linked with performance.
 A benefit of blockchains in this respect is that the desired behavior of miners or validators can be verified on-chain.
 Enforcing atomicity in decentralized data-focused networks is more challenging:
-it is non-trivial to prove that a certain piece of data was sent or received.
+it is non-trivial to prove that a certain piece of data has been relayed.
 
 Our goal is to combine monetary and reputation-based incentives for Waku.
 Monetary incentives have demonstrated their robustness in blockchains.
@@ -86,24 +86,19 @@ We think they are necessary to scale the network beyond the initial phase when i
 
 ## Waku Store
 
-In this document, we focus on i13n for Waku Store.
+Waku Store is a light protocol for querying historic messages.
-
+It currently works as follows:
-Store is a client-server protocol that currently works as follows:
 1. the client sends a `HistoryQuery` to the server;
 2. the server sends a `HistoryResponse` to the client.
 
 The response may be split into multiple parts, as specified by pagination parameters in `PagingInfo`.
 
-Let us define a relevant message as a message that has been broadcast via Relay within the time frame and matching the filter criteria that the client specified.
+We define a _relevant_ message as a message that matches a client-defined filter (e.g., it has been relayed within a specified time frame).
-The desired functionality of Store can be described as following:
+Ideally, after receiving a request, a server should quickly send back a response containing all relevant messages and only them.
 
-- the server responds quickly;
+# Waku Store incentivization
-- all relevant messages are in the response;
-- the response contains only relevant messages.
 
-# Waku Store incentivization MVP
+An incentivized Store protocol has the following extra steps:
-
-We propose to add the following aspects to the protocol:
 1. pricing:
 	1. cost calculation
 	2. price advertisement
@@ -114,20 +109,31 @@ We propose to add the following aspects to the protocol:
 3. reputation
 4. results cross-checking
 
-In this document, we define the simplest viable i13n modification to the Store protocol (MVP).
+In this document, we focus on the simplest viable i13n for Store (MVP).
-The MVP protocol has no price advertisement, no price negotiation, and no results cross-checking.
+Compared to the fully-fledged protocol, the MVP version is simplified in the following ways:
-Other elements are present in a minimal version.
+- cost calculation is based on a common-knowledge price;
-In further subsections, we list the potential direction for future work towards a fully-fledged i13n protocol.
+- there is no price advertisement and no price negotiation;
+- each query is paid for in a separate transaction, `txid` acts a proof of payment;
+- the reputation system is simplified (see below);
+- there is no results cross-checking.
+
+In the MVP protocol:
+1. the client calculates the price based on the known rate per hour of history;
+2. the client pays the appropriate amount to the server's address;
+3. the client sends a `HistoryQuery` to the server alongside the proof of payment (`txid`);
+4. the server checks that the `txid` corresponds to a confirmed transaction with at least the required amount;
+5. the server sends a `HistoryResponse` to the client.
+
+In further subsections, we list the potential direction for future work towards a fully-fledged i13n mechanism.
 
 ## Pricing
 
 For MVP, we assume a constant price per hour of history.
-After the client sends a `HistoryQuery` to the server:
+This price and the blockchain address of the server are assumed to be common knowledge.
-1. The server internally calculates the offer price and sends it to the client.
+This simplifies the client-server interaction, avoiding the price negotiation step.
-2. If the client agrees, it pays and sends a proof of payment to the server.
+
-3. If the client does not agree, it sends a rejection message to the server.
+In the future versions of the protocol, the price will be negotiated and will depend on multiple parameters,
-4. If the server receives a valid payment before a certain timeout, it sends the response to the client.
+such as the total size of the relevant messages in the response.
-5. If the server receives a rejection message, or receives no message before a timeout, the server assumes that the client has rejected the offer.
 
 ### Future work
 
@@ -138,44 +144,55 @@ After the client sends a `HistoryQuery` to the server:
 
 ## Payment
 
-If the client agrees to the price, it sends a _proof of payment_ to the server.
+For the MVP, each request is paid for with a separate transaction.
-For the MVP, each request is paid for with a separate blockchain transaction.
 The transaction hash (`txid`) acts as a proof of payment.
+The server verifies the payment by ensuring that:
+1. the transaction has been confirmed;
+2. the transaction is paying the proper amount to the server's account;
+3. the `txid` does not correspond to any prior response.
 
-Note that client gives proof of payment before it receives the response.
+The client gives proof of payment before it receives the response.
 Other options could be:
 1. the client pays after the fact;
 2. the client pays partly upfront and partly after the fact;
-3. an escrow (a centralized trusted third party, or a semi-trusted entity like a smart contract) ensures atomicity .
+3. a centralized third party (either trusted or semi-trusted, like a smart contract) ensures atomicity;
+4. cryptographically ensured atomicity (similar to atomic swaps, Lightning, or Hopr).
 
 Our design considerations are:
 - the MVP protocol should be simple;
 - servers are more "permanent" entities and are more likely to have long-lived identities;
 - it is more important to protect the clients's privacy than the server's privacy.
 
-In light of these criteria, we suggest that the client pays first: this is simpler than splitting the payment, more secure than trusting a third party, and (arguably) more privacy-preserving for the client than the alternative where the client pays after the fact (that would encourage servers to deanonymize clients to prevent fraud).
+In light of these criteria, we suggest that the client pays first.
+This is simpler than splitting the payment, or involving an extra atomicity-enforcing mechanism.
+Moreover, pre-payment is arguably more privacy-preserving than post-payment, which encourages servers to deanonymize clients to prevent fraud.
 
 ### Future work
 
 - Add more payment methods - see https://github.com/waku-org/research/issues/58
 - Design a subscription model with service credentials - see https://github.com/waku-org/research/issues/59
 - Add privacy to service credentials - see https://github.com/waku-org/research/issues/60
+- Consider the impact of network disruptions - see https://github.com/waku-org/research/issues/65
 
 ## Reputation
 
 We use reputation to discourage the server from taking the payment and not responding.
 The client keeps track of the server's reputation:
-- all servers start with zero reputation;
+- all servers start with zero reputation points;
-- if the server honors the request, it gets +1;
+- if the server honors the request, it gets `+n` points;
-- if the server does not respond before the payment, it gets -1;
+- if the server does not respond before a timeout, it gets `-m` points.
-- if the server does not respond after the payment and before a timeout, the client will never query it again.
+- if the server's reputation drops below `k` points, the client will never query it again.
+
+`n`, `m`, and `k` are subject to configuration.
+
+Optionally, a client may treat a given server as trusted, assigning it a constant positive reputation.
 
 Potential issues:
 - An attacker can establish new server identities and continue running away with clients' money. Countermeasures:
-	- a client only queries "trusted" servers (which however leads to centralization);
+	- a client only queries trusted servers (which however leads to centralization);
-	- when querying a new server, a client first sends a small (i.e. cheap) request as a test.
+	- when querying a new server, a client first sends a small (i.e. cheap) request as a test;
+	- more generally, the client selects a server on a case-by-case basis, weighing the payment amount against the server's reputation.
 - The ban mechanism can theoretically be abused. For instance, a competitor may attack the victim server and cause the clients who were awaiting the response to ban that server. Countermeasure: prevent DoS-attacks.
-- Servers may also farm reputation by running clients and querying their own server.
 
 ### Future work
 
@@ -188,8 +205,11 @@ While rate limiting stops such attack, the server would need to link requests co
 
 ## Results cross-checking
 
-Cross-checking is absent in MVP but should be considered later.
+As there is no consensus over past messages, a client may want to query multiple servers and merge their responses.
-We can separate it into two tasks for the client: ensure that servers are a) not censoring real messages; b) not injecting fake messages into history.
+Cross-checking helps ensure that servers are a) not censoring real messages; b) not injecting fake messages into history.
+Cross-checking is absent in MVP but may be considered later.
+
+### Future work
 
 - Cross-checking the results against censorship - see https://github.com/waku-org/research/issues/57
 - Use RLN to limit fake message insertion - see https://github.com/waku-org/research/issues/38