docs: 📝 how it works and why it exists changes

docs/learn/how-it-works.md

@@ -69,9 +69,11 @@ Some of the resources provided by the Network Nodes are:
 
 ## Incentives and rewards
 
-Fleek Network issues FLK, an ERC-20 fungible token created using the Ethereum Blockchain.
+Fleek Network issues FLK–an ERC-20 fungible token created using the Ethereum Blockchain–which Node operators stake to perform work on the network. In contrast, developers and clients use stablecoins in a fair exchange for the commodities and resources consumed on the network.
 
-Node operators stake FLK tokens to perform work on the network. In contrast, developers and clients use stablecoins in a fair exchange for the commodities and resources consumed on the network.
+:::caution warning
+A Node Operator has to stake FLK to have a Node participate in the Network. A stakeless Node cannot participate, as there would be no way to punish them for malicious behavior.
+:::
 
 A Node is a process that runs on a machine that provides resources to the Network. The resources are packaged as commodities, for instance:
 - Availability
@@ -80,7 +82,7 @@ A Node is a process that runs on a machine that provides resources to the Networ
 
 These commodities are exchanged fairly and pricing is decided by the ecosystem and network governance in USD.
 
-Service providers are rewarded for fulfilling cache requests per bandwidth and by sharing cached data with other peers – as an incentive for a shared economy – therefore the more bandwidth served, the more tokens received.
+Service providers are rewarded for fulfilling cache requests per bandwidth and by sharing cached data with other peers – as an incentive for a shared economy–therefore the more bandwidth served, the more tokens received.
 
 When an epoch ends, which is about 24 hours, the rewards from all submitted Delivery Acknowledgements are distributed to the edge nodes.
 
@@ -102,7 +104,7 @@ Finally, Delivery Acknowledgements are gathered and batched by Nodes before bein
 
 The Fleek Network has a reputation system where Nodes rate each other. The ratings are collected timely and an aggregation algorithm calculates the overall rate for each Node at the end of every Epoch.
 
-Any reputation system that depends on players attributing rates to each other can be exploited. As critical, a custom version of the EigenTrust algorithm is used to reduce dishonest and incorrect measurements.
+Any reputation system that depends on players attributing rates to each other can be exploited. For prevention, a custom version of the EigenTrust algorithm is used to reduce dishonest and incorrect measurements.
 
 Some other procedures where a Node is rated are on the interactions between nodes while servicing. Meaning that a Node earns a rate per service interaction.
 
@@ -134,7 +136,7 @@ The **Client** is a user that consumes data from the network; for instance:
 - A developer interested in using the CDN in an application
 - A media publisher wanting to accelerate access to media assets
 - A system administrator looking for instructions to troubleshoot the client library
-- A Solutions Architect looking for a quick overview of an alternative service for a centralized providers
+- A Solutions Architect looking for a quick overview of an alternative service for a centralized provider
 - Instructions to install and use the client library
 - Others
 
@@ -153,11 +155,10 @@ The **Developer** is a knowledgeable user that enables the business logic and en
 
 - Protocol development contributor
 - Service creator
-- Usage of the client library
+- Client library user
 - Contributions to the client libraries and tools
 - The library method and parameters references
 - Versions and features support
-- Much more
 
 A developer is often described as a builder who enables the end-to-end experience in the Fleek Network. A builder that can work at the Service provider level, protocol development, core contributor and, amongst others, at a higher level, such as providing support and integrations of services in applications or third-party systems.
 
@@ -169,7 +170,8 @@ An **End-user** is someone to whom the data or computation output is ultimately
 - Image optimization for a very particular size request
 - Server-side rendering
 - Gets data through HTTP Gateway or RPC
-- Amongst others
+
+The service outputs are for the **end-user**, but payment for the service is the responsibility of the **client** that manages the application/service the **end-user** interacts with.
 
 ### Node operator
 
@@ -181,25 +183,24 @@ A **Node Operator** is a kind of system administrator who builds, configures, in
 - Installs the Node manually
 - Configures the Node
 - Secures the server
-- Other cases
 
 The Fleek Network works as a distributed system of nodes where each node operates and contributes to the system’s overall health and functionality with computational resources by network operation demand.
 
 Nodes are set up to run on servers by operators. Operators are system administrators who build, configure, install and maintain the nodes in a server. Generally, a node is installed and runs on a computer or virtual private server (VPS) lent by a Cloud Service Provider.
 
+:::info
 A server is a computer machine where a Node runs and can be located anywhere in the world.
+:::
 
 The Node Operator is a critical system actor that is incentivized to manage one or many nodes. Ultimately making the Fleek Network what is about, a decentralized orchestration layer and infrastructure.
 
 Any individual who's interested in learning can become a Node Operator by reading the documentation, or content made available by the Network Core team and Community.
 
 ## Multi-Service Support
 
-The Fleek Network provides a base layer as the foundation of many Services.
+The Fleek Network provides a base layer as the foundation of many Services. Simplicity at its Core, it handles Proof-of-delivery and other Client-Node exchanges, such as user balance and rewards.
 
-The Core is simple, handling Proof-of-delivery and other Client-Node exchanges, such as user balance and rewards.
-
-Design to allow anyone to create and deploy a custom Service to the Network, without having to get permission. The protocol slashing mechanisms help deter malicious behavior and penalize dishonest participants while allowing the service, a modular unit, to operate at maximum availability and performance.
+It's designed to allow anyone to create and deploy a custom Service to the Network, without the need for anyone's permission. The protocol slashing mechanisms help deter malicious behavior and penalize dishonest participants while allowing the service, a modular unit, to operate at maximum availability and performance.
 
 Within a diverse ecosystem where Node Operators are free to choose which Services to run, e.g. an operator might find popular services more appealing economically. Thus, the network is nonhomogenous, made up of different types of resource servers, requirements and services.
 
@@ -272,12 +273,12 @@ In a nutshell, this is similar to the same idea, and we represent different unit
 
 ## Identity on the Fleek Network
 
-The identity on the Fleek Network is issued and controlled by individuals, it's not issued, managed or controlled by any central entity. An identity is created without permission from anyone and stored privately.
+The identity on the Fleek Network is issued and controlled by individuals, which means that there aren't any central entities that issue, manage or control it for you. An identity is created without permission from anyone, and stored securely and privately.
 
 The types of Identities found in the Fleek Network are used for:
-- Node
-- Node Network
-- Account Owner is any actor holding a balance on Fleek Network
+- Node (for BFT DAG consensus)
+- Node Network (for fast communication signatures)
+- Account Owner (any actor holding a balance on Fleek Network)
 
 The Public-key cryptography used in the network identities are the following curves:
 - BLS12-381 is a pairing-friendly elliptic curve construction from the BLS family
@@ -286,11 +287,87 @@ The Public-key cryptography used in the network identities are the following cur
 
 The identities are associated with the elliptic curves as follows:
 - A Node key is BLS12-381 which facilitates the consensus algorithm or persistence of state, resilience and fault tolerance. Has multi-signature support, the ability to aggregate many signatures into one used for consensus committee when signing certificates
-- A Node Networking key is Ed25519 used for the speed and performance of the network communication
+- A Node Networking key is Ed25519 used for the speed and performance of the network communications
 - Account Owner keys are based on secp256k1, which corresponds to an Ethereum Address
 
 Transactions can be signed by the Account Owner and Node identities.
 
-Node Networking with Narwhal used the Node Network key, as Ed25519 is much more efficient when dealing with a single signature instead of aggregated signatures.
+Node Networking with Narwhal utilizes the Node Network key, as Ed25519 is much more efficient when dealing with a single signature instead of aggregated signatures.
+
+The Account Owner (secp256k1) is an Ethereum key the user has and uses on an external wallet. It's required to initially bridge assets from L2. Although, a node doesn't need this key on its server to function.
+
+## Content addressability and verifiability
+
+The way content is handled, stored and distributed defines how trustworthy's a protocol. Some of the primitives to achieve it has roots in immutability, verification, the Semantic Web and Linked Data.
+
+When you use Fleek Network, you either hint about data packed into a format called a Content Archive (CAR) or an existing CID of a CAR file, which hash addresses are unique and universally addressable. The network never stores data, only a cache layer to existing storage as origins. For example, on `HTTP PUT` we're just telling the network that there's some origin it should care about and cache.
+
+Some of the principles that help us provide guarantees to end-users require a high ability for content verification, as a consequence, the immutability of files is critical to the system.
+
+:::info
+To emphasize, immutability means the state of not changing, or being unable to change!
+:::
+
+### Immutability
+
+Fleek Network deals with files in a manner where the content determines the address in which the user of the system can locate and verify it unquestionably. This is possible due to cryptography, in which the same data always produces the same hash deterministically.
+
+- A file whose content determines the hash, but is also impossible to invert it
+- We shouldn't be able to reconstruct the data from a hash
+- It's unique, not two files produce the same file or content
+- Any change in the content should always generate a completely different hash
+
+In retrospect, what we have on the web today are files accessible via a URL address and the problem with this approach is that the content is not intrinsically tight to the address e.g. the content can change and the URL remains the same. That is the problematic way we access files on the web today, which we call "Location addressing", and the way we solve it for the web of tomorrow is called "Content addressing".
+
+### Content addressing
+
+Content addressing is where we use a hash to access the content, and it allows us to verify that the content we received is the content we asked for. For this, we use a special hash called CID (Content Identifier), a cryptography hash function that maps input of arbitrary size to the output of a fixed size—the content identifiers are short, regardless of the size of the content, and the address does not tell us where the content is stored.
+
+The entire network operates based on content addressing based on Blake3 hashing for efficient content identification and streaming verifiability.
+
+:::info
+It's also interesting to observe, that the CID is a sort of string-like binary that is human-friendlier in comparison to the underlying binary, which is way longer.
+:::
+
+:::info
+Caching and deduplication are possible due to the immutability of content e.g. if content changes, let's say that an image has some new detail, the files share many of the same bytes. The amount of data we have to transfer to fetch is minimum, we'd only pull the difference. In today's web, we'd have to transfer both files in full, which is a worse path on resource allocation and performance.
+:::
+
+
+### Hash functions
+
+The hash function for creating CIDs uses sha-256, but there is support for other hashing algorithms, such as sha1 (used by Git), sha2-256, sha3-255, blake2b-160, blake3, etc. Some older algorithms are proven not to be collision-free, so if algorithms can break, we have to switch the hash algorithm we use in the future! The problem with this switching of algorithms is the need to find a future-proof way of identifying the hash functions used to generate the hash, as well as the hash name.
+
+Multihash is a protocol that comes into play to provide us the valuable metadata for future-proofing. To explain it in simple terms: it is the composition where a hash is placed at the end, a prefix as a number to identify the algorithm used and a number to identify the hash name. Thereafter, we'd start raising some questions. Without it, how would we get the data back without the ability to identify how it was encoded? Some users could use cbor, protocol buffers, json, etc; and there might be plenty of good reasons why for those choices. Maybe it's a compact binary encoding that is very efficient for storage, easy to work with, etc.
+
+What's important is that it is the user's choice and why IPLD becomes useful for Fleek Network's use cases. A system for understanding and working with data that is made of a Data Model and Codecs, some tools for Linking, and then a handful of other Powerful Features that help us develop a decentralized application.
+
+### Interplanetary linked data (IPLD)
+
+Interplanetary linked data (IPLD) provides us with all the metadata prefixes to soothe the system needs, and provides us with the data model of the content-addressable web, as discussed earlier. IPLD is a set of conventions for creating decentralized data structures that are universally addressable and linkable.
+
+A Distributed Hash Table (DHT) enables the network to store an IPLD or flexible mapping from any "immutable data pointer", such as a CID to its corresponding Blake3 hash. As mentioned in the [Content Addressing](#content-addressing) section, the network operates over Blake3 hashing for efficient content handling.
+
+:::info
+These addressable and linkable data structures will allow us to do for data what URLs and links did for HTML web pages (Quote from IPLD).
+:::
+
+### Content Addressable aRchive (CAR)
+
+The core of Fleek Network understands the IPLD CAR Content Addressable aRchive, which unpacks and traverses to cache individual files. The archive's content is hashed as Blake3, which Fleek Network uses to address all data coming and going into the network, regardless of their origin.
+
+:::caution warning
+Despite handling IPLD CAR files, it serves raw archive content to the client. In other words, if a request for a complete CAR came through a Gateway, the Gateway–as a client–would have to build the file from the streamed data before sending it to the end-user.
+:::
+
+:::info
+The ordering of blocks in a CAR is random, e.g. two different CAR files storing the same content. This causes need to traverse the archive (DAG-PB/UnixFS) to store the CAR blocks as individual content
+:::
+
+### HTTP PUT Request Origin
+
+An **Origin** is a location where content originates from. In the context of Fleek Network, the origin has to be supported for data retrieval, some examples that should be supported are Arweave, Filecoin and IPFS. For example, a user of Fleek Network should have the data pinned for IPFS somewhere to have it cached by the Fleek Network CDN service on an `HTTP PUT` request.
 
-The Account Owner (secp256k1) is an Ethereum key the user has and uses on an external wallet. It's required to initially bridge assets from L2. Although, a node doesn't need this key on its server to function.
+:::info
+A Client-side library can provide helpers to upload to some origin, such as IPFS and call the `HTTP PUT` for the origin.
+:::

docs/learn/why-it-exists.md

@@ -19,7 +19,7 @@ The Fleek Network provides the alternative, paving the way to a decentralized ed
 
 The original vision for the Internet was to build a network where everyone could participate, access and share information. But this was compromised after individuals and organizations found ways to trap and monetize information gathered from users.
 
-Thankfully, the emerging movement to break free from centralization, and privacy concerns, resembles the original vision of the Internet. A decentralized Web, which's often referred to as Web 3, where building services are free of central authorities.
+Thankfully, the emerging movement to break free from centralization, and privacy concerns, resembles the original vision of the Internet. A decentralized Web, which's often referred to as Web3, where building services are free of central authorities.
 
 A Decentralized Web envisions a world where services are powered by the community.