Merge pull request #2373 from filecoin-project/What-is-Filecoin-Revisions

What is filecoin revisions

Author: robertagora

basics/what-is-filecoin/README.md

@@ -3,15 +3,19 @@ description: >-
   This section offers a detailed overview of Filecoin for developers, serving as a go-to reference for their needs.
 ---
 
+<meta name="description" content="Introduction to Filecoin." />
+
 # Introduction to Filecoin
 
-Filecoin is a peer-to-peer network that enables reliable, decentralized file storage through built-in economic incentives and cryptographic proofs. Users pay storage providers—computers that store and continuously prove file integrity—to securely store their files over time. Anyone can join Filecoin as a user seeking storage or as a provider offering storage services. Storage availability and pricing aren’t controlled by any single entity; instead, Filecoin fosters an open market for file storage and retrieval accessible to all.
+Filecoin is a peer-to-peer network that enables reliable, decentralized file storage through built-in economic incentives and cryptographic proofs. Clients, or users, pay any number of storage providers, or data centers, to store the client's data --storage providers then provide cryptographic proofs daily as evidence to the clients that the data is still at the data center.  Storage providers lock a certain amount of Filecoin as collateral --should they repeatedly fail to provide a proof, their collateral gets burned, serving as a strong deterrent from the data center losing the data. 
+
+Anyone can join Filecoin as a client looking to store their data, or as a storage provider offering storage services. Storage availability and pricing aren’t controlled by any single entity; instead, Filecoin fosters an open market for file storage and retrieval accessible to all.  Clients can review the history of each storage provider, along with their credentials and compliance record, before choosing to store their data with them.
 
-Filecoin is built on the same technology as the [IPFS protocol](https://docs.ipfs.tech/). IPFS is a distributed storage network that uses [content addressing](https://docs.ipfs.tech/concepts/content-addressing/) to provide permanent data references without dependency on specific devices or cloud providers. Filecoin differs from IPFS by introducing an incentive layer that promotes reliable storage and consistent access to data.
+Note that most Filecoin nodes are [IPFS protocol](https://docs.ipfs.tech/) nodes.  IPFS is a open system, a hypermedia protocol, to manage data without a central server that makes use of [content addressing](https://docs.ipfs.tech/concepts/content-addressing/) to provide permanent data references without dependency on specific devices or cloud providers.  A client who knows the content address (CID) of their file can retrieve it from any IPFS node (or Filecoin storage provider) that currently has a copy and is able to serve it.  Given a CID, the [CID Contact](https://cid.contact/) network indexer will locate and providing routing details for the relevant file.   
 
-Filecoin’s use cases are diverse, ranging from Web3-native NFT storage to metaverse and gaming assets, as well as incentivized, permanent storage. It also offers a cost-effective solution for archiving traditional Web2 datasets, making it a strong alternative to conventional cloud storage.
+Historically, IPFS node operators offered pinning services to the community out of interest and often for free, meaning there was no financial incentive for the IPFS node operators to stay online or keep a given file for a long period of time.  Filecoin solves this issue by introducing an incentive layer (clients pay storage providers for long term data center use) to ensure more reliable long term cold storage.  Since most Filecoin nodes are also IPFS nodes, they can pin a hot copy of the given file to the IPFS node to allow the client to easily retrieve the file later.
 
-For instance, [NFT.Storage](https://nft.storage/) leverages Filecoin for decentralized NFT content and metadata storage. Likewise, organizations like the [Shoah Foundation](https://sfi.usc.edu/) and the [Internet Archive](https://archive.org/) use Filecoin for content preservation and backup.
+Filecoin is used as a storage solution for a range of products, including from Web3-native NFT storage, incentivized permanent storage, and archival traditional Web2 datasets. For instance, [NFT.Storage](https://nft.storage/) leverages Filecoin for NFT content and metadata storage.  Organizations such as the [Shoah Foundation](https://sfi.usc.edu/) and the [Internet Archive](https://archive.org/) use Filecoin for content preservation and backup.
 
 Filecoin is compatible with various data types, including audio and video files. This versatility allows Web3 platforms like [Audius](https://audius.co/) and [Huddle01](https://huddle01.com/) to use Filecoin as a decentralized storage backend for music streaming and video conferencing.
 

basics/what-is-filecoin/blockchain.md

@@ -3,23 +3,22 @@ description: >-
   A blockchain is a distributed database shared among nodes in a computer network. This page covers the design and functions of the Filecoin blockchain.
 ---
 
+<meta name="description" content="The filecoin blockchain and how it works." />
+
 # Blockchain
 
 ## Tipsets
 
-The Filecoin blockchain consists of a chain of tipsets rather than individual blocks. A tipset is a set of blocks with the same height and parent tipset, allowing multiple storage providers to produce blocks in each epoch to increase network throughput.
-
-Each tipset is assigned a weight, enabling the consensus protocol to guide nodes to build on the heaviest chain. This adds a level of security to the Filecoin network by preventing interference from nodes attempting to produce invalid blocks.
+A tipset is a set of blocks with the same height, allowing multiple storage providers to produce blocks in each epoch, increasing network throughput.  The Filecoin blockchain consists of a chain of tipsets rather than individual blocks.  Each tipset is assigned a weight, enabling the consensus protocol to guide nodes to build on the heaviest chain and preventing interference from nodes attempting to produce invalid blocks.
 
 ## Actors
 
-An actor in the Filecoin blockchain is similar to a smart contract in the Ethereum Virtual Machine. It functions as an ‘object’ within the Filecoin network, with a state and a set of methods for interaction.
+Actors are ‘objects’ within the Filecoin network, each with a state and a set of methods for interaction, that pass messages to each other and ensure the system operates appropiately.
 
 ### Built-in actors
 
 Several built-in system actors power the Filecoin network as a decentralized storage network:
 
-- **System actor**: General system actor.
 - **Init actor**: Initializes new actors and records the network name.
 - **Cron actor**: Scheduler that runs critical functions at every epoch.
 - **Account actor**: Manages user accounts (non-singleton).
@@ -33,14 +32,7 @@ Several built-in system actors power the Filecoin network as a decentralized sto
 - **Verified registry actor**: Manages verified clients.
 - **Ethereum Address Manager (EAM) actor**: Assigns Ethereum-compatible addresses on Filecoin, including EVM smart contract addresses.
 - **Ethereum Virtual Machine (EVM) account actor**: Represents an external Ethereum identity backed by a secp256k1 key.
-
-### User-programmable actors
-
-With the maturity of the FVM, developers can write actors and deploy them on the Filecoin network, similar to other blockchains' smart contracts. User-programmable actors can interact with built-in actors via the exported API from built-in actors.
-
-## Distributed randomness
-
-Filecoin uses the [Drand](https://drand.love) protocol as a randomness beacon for leader election in the [expected consensus](blockchain.md#expected-consensus) process. This randomness ensures leader election is secret, fair, and verifiable.
+- **System actor**: General system actor.
 
 ## Nodes
 
@@ -58,7 +50,7 @@ In the Filecoin network, addresses identify actors in the Filecoin state. Each a
 
 - **`f0/t0`**: ID address for an actor in a human-readable format, such as `f0123261` for a storage provider.
 - **`f1/t1`**: secp256k1 wallet address, generated from an encrypted secp256k1 public key.
-- **`f2/t2`**: Address assigned to an actor (smart contract) in a way that ensures stability across network forks.
+- **`f2/t2`**: Address assigned to an actor in a way that ensures stability across network forks.
 - **`f3/t3`**: BLS wallet address, generated from a BLS public key.
 - **`f4/t4`**: Address created and assigned to user-defined actors by customizable "address management" actors. This address can receive funds before an actor is deployed.
 - **`f410/t410`**: Address space managed by the Ethereum Address Manager (EAM) actor, allowing Ethereum-compatible addresses to interact seamlessly with the Filecoin network. Ethereum addresses can be cast as `f410/t410` addresses and vice versa, enabling compatibility with existing Ethereum tools.
@@ -67,9 +59,11 @@ In the Filecoin network, addresses identify actors in the Filecoin state. Each a
 
 ### Expected consensus
 
-Expected Consensus (EC) is the consensus algorithm underlying Filecoin. EC is a probabilistic, Byzantine fault-tolerant protocol that conducts a leader election among storage providers each epoch to determine which provider submits a block. Similar to proof-of-stake, Filecoin’s leader election relies on proof-of-storage, meaning the probability of being elected depends on how much provable storage power a miner contributes to the network. This storage power is recorded in the storage power table, managed by the Storage Power Actor.
+Expected Consensus (EC) is the probabilistic, Byzantine fault-tolerant consensus algorithm underlying Filecoin. EC conducts a leader election among storage providers each epoch to determine which provider submits a block.  Similar to proof-of-stake, Filecoin’s leader election relies on proof-of-storage, meaning the probability of being elected depends on how much provable storage a miner contributes to the network --measured in something called "storage power".
+
+The consensus process uses [Drand](https://drand.love) as a randomness beacon for leader election, ensuring the leader election is secret, fair, and verifiable.  Election participants and their storage power are drawn from a data structure called the "Power Table", which is continuously calculated and maintained by the storage power actor. 
 
-At a high level, the consensus process uses [Drand](https://drand.love) to provide distributed, verifiable randomness, ensuring that leader election is secret, fair, and unbiased. Election participants and their storage power are drawn from the Power Table, which is continuously calculated and maintained by the Storage Power Consensus subsystem. Ultimately, EC gathers all valid blocks produced in an epoch and applies a weighting function to select the heaviest chain, adding blocks accordingly.
+Ultimately, the EC process ends by gathering all valid blocks produced in an epoch to a tipset, applying a weighting function to select the heaviest chain, and adding the tipset to the heaviest chain accordingly.
 
 ### Block production process
 
@@ -80,7 +74,7 @@ The block production process for each epoch is as follows:
 - Elected miners generate WinningPoSt using randomness.
 - Miners build and propagate a block.
 - Verify the winning miner and election.
-- Select the heaviest chain to add blocks.
+- Select the heaviest chain to add the tipset.
 
 ### Finality
 

basics/what-is-filecoin/retrieval-market.md

@@ -5,7 +5,7 @@ description: >-
 
 # Retrieval market
 
-## Basic retrieval
+## Basic Retrieval from Filecoin
 
 Currently, Filecoin nodes support direct retrieval from the storage miners who originally stored the data. Clients can send retrieval requests directly to a storage provider and pay a small amount of FIL to retrieve their data.
 
@@ -15,8 +15,8 @@ To request data retrieval, clients need to provide the following information to
 - **Payload CID**: Also known as Data CID.
 - **Address**: The address initially used to create the storage deal.
 
-## Saturn
+## Hot Retrieval from IPFS
 
-[Saturn](https://saturn.tech/) is a Web3 CDN within Filecoin’s retrieval market that serves data stored on Filecoin with low latency and at a low cost. It consists of independent retrieval providers dedicated to efficient, fast, and reliable data retrieval operations.
+Since most Filecoin nodes are also IPFS nodes, standard practice has been for Filecoin storage providers to also make available a hot copy of any given stored file through IPFS.  Since the algorithm that generates a content address (CID) is the same for both Filecoin and IPFS, the client can request the CID of a file they stored on Filecoin and retrieve it from IPFS, if there is an IPFS node that is able and willing to serve the file. 
 
 [Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/basics/what-is-filecoin/retrieval-market)